Visual Basic Toolbox/Visual Basic Toolbox (P.I.E.)(1996).ISO/dll_io/vbpxen/readme.txt

Text File | 1992-01-03 | 16KB | 441 lines

                                PREFACE


I am placing this code and documentation in the public domain in the
hopes that others may find it useful. You are free to use, modify and
distribute it as you see fit.  This code is provided on an as-is
basis; I have tested much of it but it is not guaranteed to be bug-
free.  If you find errors or have suggestions for improvement, you can
send them to me if you'd like.

Sharon F. Dooley
January 2, 1992
CompuServe ID 70740,2330

PAL and PARADOX are trademarks of Borland.  Visual Basic is a
trademark of Microsoft.




              A VISUAL BASIC -- PARADOX ENGINE INTERFACE



Introduction

This Visual Basic interface to the Paradox Engine insulates the VB
programmer from some of the quirks of the Paradox Engine as well as
from some of the differences between VB and a C DLL.  It also permits
the VB programmer to work with VB's native data types while
simultaneously allowing the Paradox user or PAL (Paradox Application
Language) programmer to work with the native Paradox data types.  For
example, VB has a wealth of date manipulation functions that want the
VB date-serial date format.  The PAL date functions naturally expect a
Paradox date format.  The interface layer translates to and from the
database format as data is retrieved from or stored in a Paradox
table.  The separate interface layer also provides a measure of
independence from the particular DBMS.

VB programmers can access the engine by calling a set of functions
which parallel the engine's C functions.  For convenience, these
routines have the same name as the engine functions with the prefix
VB.  For example, VBPXGetShort calls the engine's PXGetShort.

This document assumes that the reader has a working knowledge of the
engine functions, Paradox database constructs, and Visual Basic.  It
also assumes that user of the package will be moderately curious and
willing to look at the supplied code if the documentation isn't clear.

This package contains two files in addition to this documentation.
The first, VBPXGLOB.TXT, contains declarations of global constants
that the VB programmer can use.  These global constants include
TypeDefs for the various objects the engine uses: handles, buffers,
etc., mnemonics for the engine's error codes, and some of the 'words'
used by engine functions such as SEARCHFIRST, SEARCHNEXT.  The
interface layer assumes these definitions are global.  If you do not
want to use them, add them to the module that contains VBPXENG.TXT.
If you also want to use them, add them to your global module.  The
second file is VBPXENG.TXT.  This file contains a few constants used
only by the VBPX... routines, the declarations for the Paradox Engine
DLL, and the VBPX... functions.  Note that this is a TEXT file.  To
use it in your VB application, you should create a new module file.
Next,  use the load text option from the code menu to place this text
into the file.  Like their Engine counterparts, the VBPX... routines
all return an integer containing a Paradox status code.  Your programs
should always test this and handle the error if there is one.  I have
included a function that puts up a message box with the error message
text.  You will probably find this useful for debugging.

The following sections list the VBPX... functions together with their
arguments.  For convenience, I have organized them into the categories
used in the Paradox Engine documentation.  If the function simply
calls a Paradox function, only the name of that function is given.  In
this case, the VB function simply passes the arguments along to the
engine.  You can read the description of the function in the Engine
documentation.  If the function transforms data or is different in
some way from the Engine function that it calls, there is a brief
description of the differences.


INITIALIZATION AND FINALIZATION FUNCTIONS

Function VBPXExit() As Integer
     Invokes PXExit.

Function VBPXGetDefaults (swapSize As Integer, maxTables As Integer,
maxRecBufs As Integer, maxLocks As Integer, maxFiles As Integer,
sortOrder As String) As Integer
     Invokes PXGetDefaults

Function VBPXNetInit (netNamePath As String, netType As Integer,
UserName As String) As Integer
     Invokes PXNetInit; not generally used in Windows

Function VBPXSave () As Integer
     Invokes PXSave

Function VBPXSetDefaults (bufSize As Integer, maxTables As Integer,
maxRecBufs As Integer, maxLocks As Integer, maxFiles As Integer,
sortOrder As String) As Integer
     Invokes PXSetDefaults; note that there are defined constants
     for sort order in VBPXGLOB.TXT.  This may not be useful
     because you need to run the engine configuration program to
     tell Windows what your maxima are, but the engine
     documentation is unclear, so here it is.

Function VBPXWinInit (ClientName As String, ShareMode As Integer) As
Integer
     Invokes PXWinInit


TABLE FUNCTIONS

Function VBPXTblAdd (srcTableName As String, destTableName As String)
As Integer
     Invokes PXTblAdd

Function VBPXTblClose (table As TABLEHANDLE) As Integer
     Invokes PXTblClose

Function VBPXTblCopy (srcTableName As String, destTableName As String)
As Integer
     Invokes PXTblCopy

Function VBPXTblCreate (TableName As String, NumFields As Integer,
Fields() As String, Types() As String) As Integer
     Fields and Types are simple VB String arrays of NumFields
     entries.  This routine handles all the conversion of these
     arrays into the Engine's required array of pointers to
     character.  Invokes PXTblCreate.

Function VBPXTblDelete (TableName As String) As Integer
     Invokes PXTblDelete

Function VBPXTblEmpty (TableName As String) As Integer
     Invokes PXTblEmpty

Function VBPXTblMaxSize (maxTblSize As Integer) As Integer
          Invokes PXTblMaxSize

Function VBPXTblName (table As TABLEHANDLE, TableName As String) As
Integer
     Returns the table name as a VB String

Function VBPXTblOpen (TableName As String, table As TABLEHANDLE,
indexId As Integer, saveEveryChange As Integer) As Integer
     Invokes PXTblOpen.  Remember that Paradox uses 1 for TRUE,
     so use a constant 1 for saveEveryChange if you want it,
     otherwise use a zero.

Function VBPXTblRename (srcTableName As String, destTableName As
String) As Integer
     Invokes PXTblRename


RECORD FUNCTIONS

Function VBPXRecAppend (table As TABLEHANDLE, Record As RECORDHANDLE)
As Integer
     Invokes PXRecAppend

Function VBPXRecBufClose (Record As RECORDHANDLE) As Integer
     Invokes PxRecBufClose

Function VBPXRecBufCopy (SrcRecord As RECORDHANDLE, DestRecord As
RECORDHANDLE) As Integer
     Invokes PXRecBufCopy

Function VBPXRecBufEmpty (Record As RECORDHANDLE) As Integer
     Invokes PXRecBufEmpty

Function VBPXRecBufOpen (table As TABLEHANDLE, Record As RECORDHANDLE)
As Integer
     Invokes PXRecBufOpen

Function VBPXRecDelete (table As TABLEHANDLE) As Integer
     Invokes PXRecDelete

Function VBPXRecFirst (table As TABLEHANDLE) As Integer
     Invokes PXRecFirst

Function VBPXRecGet (table As TABLEHANDLE, Record As RECORDHANDLE) As
Integer
     Invokes PXRecGet

Function VBPXRecGoto (table As TABLEHANDLE, Record As RECORDHANDLE) As
Integer
     Invokes PXRecGoTo

Function VBPXRecInsert (table As TABLEHANDLE, Record As RECORDHANDLE)
As Integer
     Invokes PXRecInsert

Function VBPXRecLast (table As TABLEHANDLE) As Integer
     Invokes PXRecLast

Function VBPXRecNext (table As TABLEHANDLE) As Integer
     Invokes PXRecNext

Function VBPXRecNum (table As TABLEHANDLE, RNum As RECORDNUMBER) As
Integer
     Invokes PXRecNum

Function VBPXRecPrev (table As TABLEHANDLE) As Integer
     Invokes PXRecPrev

Function VBPXRecUpdate (table As TABLEHANDLE, Record As RECORDHANDLE)
As Integer
     Invokes PXRecUpdate


FIELD FUNCTIONS

Function VBPXFldBlank (Record As RECORDHANDLE, Field As FIELDHANDLE)
As Integer
     Unlike the engine function, which places the truth value of
     the blank comparison in a separate variable, this function
     returns TRUE (-1) if field is blank, 0 if field is not
     blank, error code otherwise.  It invokes PXFldBlank.

Function VBPXFldHandle (table As TABLEHANDLE, fldName As String, Field
As FIELDHANDLE) As Integer
     Invokes PXFldHandle

Function VBPXFldName (table As TABLEHANDLE, Field As FIELDHANDLE,
fldName As String) As Integer
     Invokes PXFldName

Function VBPXFldType (table As TABLEHANDLE, Field As FIELDHANDLE,
fldType As String) As Integer
     Calls PXFldType and places a VB String in fldType

Function VBPXGetAlpha (Record As RECORDHANDLE, Field As FIELDHANDLE,
dest As String) As Integer
     If the PXGetAlpha call is successful, strips the null
     terminator and returns a true VB string in dest.

Function VBPXGetCurrency (Record As RECORDHANDLE, Field As
FIELDHANDLE, Value As Currency) As Integer
     Converts a Paradox Double to a VB Currency

Function VBPXGetDate (Record As RECORDHANDLE, Field As FIELDHANDLE,
dateval As Double)
     Gets a Paradox date and converts it to a VB Date Serial

Function VBPXGetDoub (Record As RECORDHANDLE, Field As FIELDHANDLE,
Value As Double) As Integer
     Invokes PXGetDoub

Function VBPXGetLong (Record As RECORDHANDLE, Field As FIELDHANDLE,
Value As Long) As Integer
     Invokes PXGetLong

Function VBPXGetShort (Record As RECORDHANDLE, Field As FIELDHANDLE,
Value As Integer) As Integer
     Invokes PXGetShort

Function VBPXPutAlpha (Record As RECORDHANDLE, Field As FIELDHANDLE,
Value As String) As Integer
     Invokes PXPutAlpha

Function VBPXPutBlank (Record As RECORDHANDLE, Field As FIELDHANDLE)
As Integer
     Invokes PXPutBlank

Function VBPXPutCurrency (Record As RECORDHANDLE, Field As
FIELDHANDLE, Value As Currency) As Integer
     Converts a VB Currency variable to a double and puts it into
     the record buffer with PXPutDoub

Function VBPXPutDate (Record As RECORDHANDLE, Field As FIELDHANDLE,
dateval As Double) As Integer
     converts a VB date serial to a Paradox Date field and puts
     it into the record buffer with PXPutDate

Function VBPXPutDoub (Record As RECORDHANDLE, Field As FIELDHANDLE,
Value As Double) As Integer
     Invokes PXPutDoub

Function VBPXPutLong (Record As RECORDHANDLE, Field As FIELDHANDLE,
Value As Long) As Integer
     Invokes PXPutLong

Function VBPXPutShort (Record As RECORDHANDLE, Field As FIELDHANDLE,
Value As Integer) As Integer
     Invokes PXPutShort


KEY AND INDEX FUNCTIONS

Function VBPXKeyAdd (tblName As String, nflds As Integer, Fields() As
FIELDHANDLE, IndexType As Integer) As Integer
     Invokes PXKeyAdd.  Constants for IndexType are defined in
     VBPXGLOB.

Function VBPXKeyDrop (tblName As String, indexId As Integer) As
Integer
     Invokes PXKeyDrop


SEARCH FUNCTIONS

Function VBPXSrchFld (table As TABLEHANDLE, Record As RECORDHANDLE,
Field As FIELDHANDLE, SearchMode As Integer) As Integer
     Invokes PXSrchFld.  Constants for SearchMode are defined in
     VBPXGLOB.

Function VBPXSrchKey (table As TABLEHANDLE, Record As RECORDHANDLE,
nflds As Integer, SearchMode As Integer) As Integer
     Invokes PXSrchKey.  Constants for SearchMode are defined in
     VBPXGLOB.


PASSWORD/SECURITY FUNCTIONS

Function VBPXPswAdd (Password As String) As Integer
     Invokes PXPswAdd.

Function VBPXPswDel (Password As String) As Integer
     Invokes PXPswDel.

Function VBPXTblDecrypt (TableName As String) As Integer
     Invokes PXTblDecrypt.

Function VBPXTblEncrypt (TableName As String, Password As String) As
Integer
     Invokes PXTblEncrypt

Function VBPXTblProtected (TableName As String) As Integer
     Invokes PXTblProtected and returns TRUE if table is
     protected, FALSE if not, otherwise, it returns an error code


INFORMATION FUNCTIONS

Function VBPXKeyNFlds (table As TABLEHANDLE, nKeyFlds As Integer) As
Integer
     Invokes PXKeyNFlds

Function VBPXRecNFlds (table As TABLEHANDLE, nflds As Integer) As
Integer
     Invokes PXRecNFlds

Function VBPXTblExist (TableName As String) As Integer
     Invokes PXTblExist and returns TRUE if table exists, FALSE
     if table doesn't exist, otherwise, a Paradox Error Code

Function VBPXTblNRecs (table As TABLEHANDLE, NRecs As RECORDNUMBER) As
Integer
     Invokes PXTblNRecs


NETWORK/CONCURRENCY FUNCTIONS

Function VBPXNetFileLock (fileName As String, lockType As Integer) As
Integer
     Invokes PXNetFileLock

Function VBPXNetFileUnlock (fileName As String, lockType As Integer)
As Integer
     Invokes PXNetFileLock

Function VBPXNetRecGotoLock (table As TABLEHANDLE, PXlock As
LOCKHANDLE) As Integer
     Invokes PXNetRecGotoLock

Function VBPXNetRecLock (table As TABLEHANDLE, PXlock As LOCKHANDLE)
As Integer
     Invokes PXNetRecLock

Function VBPXNetRecUnlock (table As TABLEHANDLE, PXlock As LOCKHANDLE)
As Integer
     Invokes PXNetRecUnlock

Function VBPXNetRecLocked (table As TABLEHANDLE) As Integer
     Invokes PXNetRecLocked and returns TRUE (-1) if the current
     record of table is locked, FALSE if it is not locked, and
     otherwise an error code.

Function VBPXNetTblChanged (table As TABLEHANDLE) As Integer
     Invokes PXNetTblChanged, and returns TRUE (-1) if table has
     changed.  Returns FALSE if table hasn't changed; otherwise
     it returns an error code.

Function VBPXNetTblLock (table As TABLEHANDLE, lockType As Integer) As
Integer
     Invokes PXNetTblLock

Function VBPXNetTblRefresh (table As TABLEHANDLE) As Integer
     Invokes PXNetTblRefresh

Function VBPXNetTblUnlock (table As TABLEHANDLE, lockType As Integer)
As Integer
     Invokes PXNetTblUnlock

Function VBPXNetUserName (UserName As String) As Integer
     Invokes PXNetUserName and, if successful, returns the name
     as a VB string.  Otherwise, it returns an error code.


ERROR FUNCTIONS

Function VBPXERRMSG (errcode As Integer) As String
     Calls PXErrMsg and returns the text for a Paradox Error code
     as a VB string

Function VBPXNetErrUser (UserName As String) As Integer
     Calls PXNetErrUser and returns the user name as a VB string.

Function showPDOXError (errcode As Integer) As Integer
     puts up a message box with the stop icon and the text of the
     error.  Program stops after you click ok on the  msg box so
     you can explore with the debugger, then, if you continue,
     it calls VBPXExit so you can get out cleanly.


BLANK FIELD FUNCTIONS

Sub BLANKSHORT (X As Integer)
     Places a Paradox Short Blank in X

Sub BLANKDATE (X As Double)
     Places a Paradox Blank Date in X

Sub BLANKLONG (X As Long)
     Places a Paradox Blank Long in X

Note: VBISBLANK... Functions return a VB TRUE if the the field is
blank otherwise they return a VB FALSE

Function VBISBLANKSHORT (X As Integer) As Integer
Function VBISBLANKLONG (X As Long) As Integer
Function VBISBLANKDOUBLE (X As Double) As Integer
Function VBISBLANKDATE (X As Double) As Integer

See also VBPXFldBlank, VBPXPutBlank